timestring

What is timestring?

The timestring npm package is a utility for parsing human-readable time strings into milliseconds. It allows users to convert strings like '2 days', '3 hours', or '5 minutes' into a numerical representation of time in milliseconds, which can be useful for scheduling, time calculations, and more.

What are timestring's main functionalities?

Parse time strings to milliseconds

This feature allows you to convert a human-readable time string into milliseconds. For example, '2 days' is converted to 172800000 milliseconds.

const timestring = require('timestring');
const milliseconds = timestring('2 days'); // returns 172800000

Support for various time units

The package supports parsing of various time units such as seconds, minutes, hours, days, weeks, months, and years. It can handle combinations of these units in a single string.

const timestring = require('timestring');
const milliseconds = timestring('3 hours 15 minutes'); // returns 11700000

Other packages similar to timestring

ms

The ms package is a utility for converting time strings to milliseconds and vice versa. It is similar to timestring in that it can parse strings like '2 days' or '3h' into milliseconds. However, ms also provides functionality to convert milliseconds back into a human-readable format, which timestring does not offer.

parse-duration

The parse-duration package is another tool for parsing human-readable time strings into milliseconds. It offers similar functionality to timestring but includes additional features such as custom time unit definitions and more flexible parsing options.

README

Timestring

Parse a human readable time string into a time based value.

Installation

npm install --save timestring

Usage

Overview

var timestring = require('timestring');

var str = '1h 15m';
var time = timestring(str);

console.log(time); // will log 4500

By default the returned time value from timestring will be in seconds.

The time string can contain as many time groups as needed:

var str = '1d 3h 25m 18s';
var time = timestring(str);

console.log(time); // will log 98718

and can be as messy as you like:

var str = '1 d    3HOurS 25              min         1   8s';
var time = timestring(str);

console.log(time); // will log 98718

Keywords

Timestring will parse the following keywords into time values:

1. ms, milli, millisecond, milliseconds - will parse to milliseconds
2. s, sec, secs, second, seconds - will parse to seconds
3. m, min, mins, minute, minutes - will parse to minutes
4. h, hr, hrs, hour, hours - will parse to hours
5. d, day, days - will parse to days
6. w, week, weeks - will parse to weeks
7. mon, mth, mths, month, months - will parse to months
8. y, yr, yrs, year, years - will parse to years

Keywords can be used interchangeably:

var str = '1day 15h 20minutes 15s';
var time = timestring(str);

console.log(time); // will log 141615

Return Time Value

By default the return time value will be in seconds. This can be changed by passing one of the following strings as an argument to timestring:

1. ms - Milliseconds
2. s - Seconds
3. m - Minutes
4. h - Hours
5. d - Days
6. w - Weeks
7. mth - Months
8. y - Years

var str = '22h 16m';

var hours = timestring(str, 'h'); // 22.266666666666666
var days = timestring(str, 'd'); // 0.9277777777777778
var weeks = timestring(str, 'w'); // 0.13253968253968254

Optional Configuration

A few assumptions are made by default:

1. There are 24 hours per day
2. There are 7 days per week
3. There are 4 weeks per month
4. There are 12 months per year

These options can be changed by passing an options object as an argument to timestring.

The following options are configurable:

1. hoursPerDay
2. daysPerWeek
3. weeksPerMonth
4. monthsPerYear

var str = '1d';
var opts = {
	hoursPerDay: 1
}

var time = timestring(str, 'h', opts);

console.log(time); // will log 1

In the example above hoursPerDay is being set to 1. When the time string is being parsed, the return value is being specified as hours. Normally 1d would parse to 24 hours (as by default there are 24 hours in a day) but because hoursPerDay has been set to 1, 1d will now only parse to 1 hour.

This would be useful for specific application needs.

Example - Employees of my company work 7.5 hours a day, and only work 5 days a week. In my time tracking app, when they type 1d i want 7.5 hours to be tracked. When they type 1w i want 5 days to be tracked etc.

var opts = {
	hoursPerDay: 7.5,
	daysPerWeek: 5
}

var hoursToday = timestring('1d', 'h', opts);
var daysThisWeek = timestring('1w', 'd', opts);

console.log(hoursToday); // will log 7.5
console.log(daysThisWeek); // will log 5

Changelog

3.2.0

• Add mon unit (@IanMitchell)